---
title: Интернационализация (i18n)
description: Узнайте, как настроить ваш сайт на Starlight для поддержки нескольких языков.
---

import { FileTree, Steps } from '@astrojs/starlight/components';

Starlight обеспечивает встроенную поддержку многоязычных сайтов, включая маршрутизацию, резервный контент и полную поддержку языков с письмом справа налево (RTL).

## Настройка i18n

<Steps>

1. Сообщите Starlight о поддерживаемых вами языках, передав свойства [`locales`](/ru/reference/configuration/#locales) и [`defaultLocale`](/ru/reference/configuration/#defaultlocale) в интеграцию Starlight:

   ```js {9-26}
   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';

   export default defineConfig({
   	integrations: [
   		starlight({
   			title: 'Моя документация',
   			// Устанавливаем «Русский» как язык по умолчанию для этого сайта
   			defaultLocale: 'ru',
   			locales: {
   				// Документация на английском в `src/content/docs/en/`
   				en: {
   					label: 'English',
   				},
   				// Документация на китайском в `src/content/docs/zh-cn/`
   				'zh-cn': {
   					label: '简体中文',
   					lang: 'zh-CN',
   				},
   				// Документация на русском в `src/content/docs/ru/`
   				ru: {
   					label: 'Русский',
   					lang: 'ru',
   				},
   			},
   		}),
   	],
   });
   ```

   `defaultLocale` будет использоваться для резервного контента и текста UI, поэтому выберите язык, на котором вы скорее всего начнете писать контент или для которого у вас уже есть материалы.

2. Создайте каталог для каждого языка в `src/content/docs/`.
   Например, для показанной выше конфигурации создайте следующие папки:

   <FileTree>

   - src/
     - content/
       - docs/
         - en/
         - ru/
         - zh-cn/

   </FileTree>

3. Теперь вы можете добавлять контент в свои языковые каталоги. Используйте одно и то же имя файла для связывания страниц на разных языках и воспользуйтесь полным набором функций i18n Starlight, включая резервный контент, уведомления о переводе и многое другое.

   Например, создайте `ru/index.md` и `en/index.md` для отображения главной страницы на русском и английском языках.

</Steps>

Для более продвинутых сценариев использования i18n Starlight также поддерживает настройку интернационализации с помощью [опции `i18n` Astro](https://docs.astro.build/ru/guides/internationalization/#%D0%BD%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0-i18n-%D0%BC%D0%B0%D1%80%D1%88%D1%80%D1%83%D1%82%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8).

### Использование корневой локали

Вы можете использовать «корневую» локаль для отображения языка без префикса i18n в его пути. Например, если русский является вашей корневой локалью, путь к странице на русском языке будет выглядеть как `/about` вместо `/ru/about`.

Чтобы установить корневую локаль, используйте ключ `root` в вашей конфигурации `locales`. Если корневая локаль также является локалью по умолчанию для вашего контента, удалите `defaultLocale` или установите его значение как `'root'`.

```js {9,11-14}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'Моя документация',
			defaultLocale: 'root', // опционально
			locales: {
				root: {
					label: 'Русский',
					lang: 'ru', // параметр lang обязателен для корневых локалей
				},
				en: {
					label: 'English',
					lang: 'en',
				},
			},
		}),
	],
});
```

При использовании локали `root` храните страницы для этого языка непосредственно в `src/content/docs/`, а не в отдельной языковой папке. Например, вот файлы домашней страницы для английского и русского языков при использовании приведённой выше конфигурации:

<FileTree>

- src/
  - content/
    - docs/
      - **index.md**
      - en/
        - **index.md**

</FileTree>

#### Одноязычные сайты

По умолчанию, Starlight является одноязычным сайтом, с английским языком. Чтобы создать сайт на другом языке, укажите его как `root` в вашей конфигурации `locales`:

```diff lang="js" {10-13}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'Моя документация',
			locales: {
				root: {
					label: 'Русский',
					lang: 'ru',
				},
			},
		}),
	],
});
```

Это позволяет вам переопределить язык по умолчанию для Starlight без включения других функций интернационализации для многоязычных сайтов, таких как выбор языка.

## Резервный контент

Starlight предполагает, что вы создадите эквивалентные страницы на всех поддерживаемых языках. Например, если у вас есть файл `en/about.md`, создайте файл `about.md` для каждого другого языка, который вы поддерживаете. Это позволяет Starlight предоставлять автоматически резервный контент для страниц, которые ещё не были переведены.

Если перевод для языка ещё не доступен, Starlight покажет читателям контент этой страницы на языке по умолчанию (установленном через `defaultLocale`). Например, если вы ещё не создали французскую версию вашей страницы «О нас» и вашим языком по умолчанию является английский, посетители `/fr/about` увидят английский контент из `/en/about` с уведомлением о том, что эта страница ещё не была переведена. Это помогает вам добавлять контент на вашем языке по умолчанию и постепенно переводить его, когда у ваших переводчиков есть время.

## Перевод заголовка сайта

По умолчанию Starlight использует одно и то же название сайта для всех языков.
Если вам нужно настроить заголовок для каждой локали, вы можете передать объект [`title`](/ru/reference/configuration/#title-обязателен) в опциях Starlight:

```diff lang="js"
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
-     title: 'Моя документация',
+     title: {
+       ru: "Моя документация",
+       'zh-CN': '我的文档',
+     },
      defaultLocale: 'ru',
      locales: {
        ru: { label: 'Русский' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
      },
    }),
  ],
});
```

## Перевод интерфейса Starlight

import LanguagesList from '~/components/languages-list.astro';
import UIStringsList from '~/components/ui-strings-list.astro';

Кроме размещения переведённых файлов с контентом, Starlight позволяет вам переводить текст интерфейсе (например, заголовок «На этой странице» в оглавлении), чтобы ваши читатели могли полностью погрузиться в ваш сайт на выбранном языке.

<LanguagesList startsSentence /> — все переведённые строки пользовательского
интерфейса на указанных языках предоставляются «из коробки», и мы приветствуем
[вклад в добавление новых
языков](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md).

Вы можете добавить переводы для дополнительных языков, которые вы поддерживаете — или переопределить наши стандартные тексты — через коллекцию данных `i18n`.

<Steps>

1. Сконфигурируйте коллекцию данных `i18n` в `src/content.config.ts`, если она ещё не настроена:

   ```diff lang="js" ins=/, (i18nLoader|i18nSchema)/
   // src/content.config.ts
   import { defineCollection } from 'astro:content';
   import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
   import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

   export const collections = {
    docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
   +  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
   };
   ```

2. Создайте файл JSON в `src/content/i18n/` для каждой дополнительной локали, для которой вы хотите добавить строки перевода интерфейса.
   Например, так можно добавить файлы перевода для арабского и русского:

   <FileTree>

   - src/
     - content/
       - i18n/
         - ar.json
         - ru.json

   </FileTree>

3. Добавьте переводы для ключей, которые вы хотите перевести, в файлы JSON. Переводите только значения, оставляя ключи на английском языке (например, `"search.label": "Поиск"`).

   Это английские значения по умолчанию для существующих строк, с которыми поставляется Starlight:

   <UIStringsList />

   Блоки кода Starlight основаны на библиотеке [Expressive Code](https://expressive-code.com/).
   Вы можете установить переводы для строк пользовательского интерфейса в том же файле JSON, используя ключи `expressiveCode`:

   ```json
   {
   	"expressiveCode.copyButtonCopied": "Copied!",
   	"expressiveCode.copyButtonTooltip": "Copy to clipboard",
   	"expressiveCode.terminalWindowFallbackTitle": "Terminal window"
   }
   ```

   Модальное окно поиска в Starlight работает с помощью библиотеки [Pagefind](https://pagefind.app/).
   Вы можете установить переводы для пользовательского интерфейса Pagefind в том же JSON-файле, используя ключи `pagefind`:

   ```json
   {
   	"pagefind.clear_search": "Clear",
   	"pagefind.load_more": "Load more results",
   	"pagefind.search_label": "Search this site",
   	"pagefind.filters_label": "Filters",
   	"pagefind.zero_results": "No results for [SEARCH_TERM]",
   	"pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
   	"pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
   	"pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
   	"pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
   	"pagefind.searching": "Searching for [SEARCH_TERM]..."
   }
   ```

</Steps>

### Расширение схемы переводов

Добавьте пользовательские ключи в словари переводов вашего сайта, установив `extend` в опциях `i18nSchema()`.
В следующем примере к ключам по умолчанию добавляется новый необязательный ключ `custom.label`:

```diff lang="js"
// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
	i18n: defineCollection({
		loader: i18nLoader(),
		schema: i18nSchema({
+			extend: z.object({
+				'custom.label': z.string().optional(),
+			}),
		}),
	}),
};
```

Дополнительную информацию о схемах коллекции контента см. в разделе [Определение схемы коллекции](https://docs.astro.build/ru/guides/content-collections/#%D0%BE%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5-%D1%81%D1%85%D0%B5%D0%BC%D1%8B-%D0%BA%D0%BE%D0%BB%D0%BB%D0%B5%D0%BA%D1%86%D0%B8%D0%B8) в документации Astro.

## Использование UI-переводов

Вы можете получить доступ к [встроенным строкам пользовательского интерфейса](/ru/guides/i18n/#перевод-интерфейса-starlight) Starlight, а также к [пользовательским](/ru/guides/i18n/#расширение-схемы-переводов) и [предоставляемым плагинами](/ru/reference/plugins/#injecttranslations) строкам пользовательского интерфейса через единый API на базе [i18next](https://www.i18next.com/).
Это включает поддержку таких функций, как [интерполяция](https://www.i18next.com/translation-function/interpolation) и [плюрализация](https://www.i18next.com/translation-function/plurals).

В компонентах Astro этот API доступен как часть [глобального объекта `Astro`](https://docs.astro.build/en/reference/api-reference/#locals) в виде `Astro.locals.t`:

```astro title="example.astro"
<p dir={Astro.locals.t.dir()}>
	{Astro.locals.t('404.text')}
</p>
```

Вы также можете использовать API в [эндпойнтах](https://docs.astro.build/ru/guides/endpoints/), где объект `locals` доступен как часть контекста [эндпойнта](https://docs.astro.build/en/reference/api-reference/#locals):

```ts title="src/pages/404.ts"
export const GET = (context) => {
	return new Response(context.locals.t('404.text'));
};
```

В контексте плагина Starlight вы можете использовать хелпер [`useTranslations()`](/ru/reference/plugins/#usetranslations) для доступа к этому API для конкретного языка.
Дополнительную информацию смотрите в [справочнике по плагинам](/ru/reference/plugins/).

### Рендеринг строки пользовательского интерфейса

Отрисовка строк пользовательского интерфейса с помощью функции `locals.t()`.
Это экземпляр функции i18next `t()`, которая принимает в качестве первого аргумента строку-ключ UI и возвращает соответствующий перевод для текущего языка.

Например, задан файл пользовательского перевода со следующим содержанием:

```json title="src/content/i18n/ru.json"
{
	"link.astro": "Документация Astro",
	"link.astro.custom": "Документация Astro о {{feature}}"
}
```

Первую строку пользовательского интерфейса можно отобразить, передав `'link.astro'` в функцию `t()`:

```astro {3}
<!-- src/components/Example.astro -->
<a href="https://docs.astro.build/">
	{Astro.locals.t('link.astro')}
</a>
<!-- Отрисовывает: <a href="...">Документация Astro</a> -->
```

Вторая строка пользовательского интерфейса использует [синтаксис интерполяции](https://www.i18next.com/translation-function/interpolation) i18next для размещения `{{feature}}`.
Значение для `feature` должно быть задано в объекте options, передаваемом в качестве второго аргумента в `t()`:

```astro {3}
<!-- src/components/Example.astro -->
<a href="https://docs.astro.build/ru/guides/astro-db/">
	{Astro.locals.t('link.astro.custom', { feature: 'Astro DB' })}
</a>
<!-- Отрисовывает: <a href="...">Документация Astro о Astro DB</a> -->
```

Подробнее о том, как использовать функцию `t()` для интерполяции, форматирования и т. д., см. в [документации i18next](https://www.i18next.com/overview/api#t).

### Расширенные API

#### `t.all()`

Функция `locals.t.all()` возвращает объект, содержащий все строки пользовательского интерфейса, доступные для текущей локали.

```astro
---
// src/components/Example.astro
const allStrings = Astro.locals.t.all();
//    ^
//    {
//      "skipLink.label": "Перейти к содержанию",
//      "search.label": "Поиск",
//      …
//    }
---
```

#### `t.exists()`

Чтобы проверить, существует ли ключ перевода, используйте функцию `locals.t.exists()` с ключом перевода в качестве первого аргумента.
Передайте необязательный второй аргумент, если нужно проверить наличие перевода для определённой локали.

```astro
---
// src/components/Example.astro
const keyExists = Astro.locals.t.exists('a.key');
//    ^ true
const keyExistsInFrench = Astro.locals.t.exists('other.key', { lngs: ['fr'] });
//    ^ false
---
```

Дополнительную информацию см. в статье [`exists()` в документации i18next](https://www.i18next.com/overview/api#exists).

#### `t.dir()`

Функция `locals.t.dir()` возвращает направление текста текущей или определённой локали.

```astro
---
// src/components/Example.astro
const currentDirection = Astro.locals.t.dir();
//    ^
//    'ltr'
const arabicDirection = Astro.locals.t.dir('ar');
//    ^
//    'rtl'
---
```

Дополнительную информацию см. в статье [`dir()` в документации i18next](https://www.i18next.com/overview/api#dir).

## Доступ к текущей локали

Вы можете использовать [`Astro.currentLocale`](https://docs.astro.build/en/reference/api-reference/#currentlocale) для получения текущей локали в компонентах `.astro`.

Следующий пример считывает текущую локаль и использует её с помощью хелпера [`getRelativeLocaleUrl()`](https://docs.astro.build/ru/reference/modules/astro-i18n/#getrelativelocaleurl) для генерации ссылки на страницу «О сайте» на текущем языке:

```astro
---
// src/components/AboutLink.astro
import { getRelativeLocaleUrl } from 'astro:i18n';
---

<a href={getRelativeLocaleUrl(Astro.currentLocale ?? 'en', 'about')}>О сайте</a>
```
